docs: Split commit message conventions from README

We currently only have a very brief outline of the commit message
conventions in the README.

Improve on that by splitting out the relevant section into a separate
file that outlines all conventions we use in addition to the general
guidelines in the [handbook].

[handbook]: https://handbook.gnome.org/development/commit-messages.html

Part-of: <https://gitlab.gnome.org/GNOME/gnome-shell/-/merge_requests/3122>

diff --git a/README.md b/README.md
index 2a9d3374062d0527671e11477b5bdff9437834dc..542ddd7f5f742f3654c419bc0cdf439ba03e32e1 100644 (file)
--- a/README.md
+++ b/README.md
@@ -17,12 +17,9 @@ All interactions with the project should follow the [Code of Conduct][conduct].
 
 To contribute, open merge requests at https://gitlab.gnome.org/GNOME/gnome-shell.
 
-Commit messages should follow the [GNOME commit message
-guidelines](https://wiki.gnome.org/Git/CommitMessages). If a merge request
-fixes an existing issue, it is good practice to append the full issue URL
-to each commit message. Try to always prefix commit subjects with a relevant
-topic, such as `panel:` or `status/network:`, and it's always better to write
-too much in the commit message body than too little.
+Commit messages should follow the [commit message guidelines][commit-messages].
+
+[commit-messages]: docs/commit-messages.md
 
 ## License
 

diff --git a/docs/commit-messages.md b/docs/commit-messages.md
new file mode 100644 (file)
index 0000000..471e48a
--- /dev/null
+++ b/docs/commit-messages.md
@@ -0,0 +1,67 @@
+# Commit Messages
+
+Commit messages should follow the guidelines in the [GNOME handbook][handbook].
+Please make sure that you have read those recommendations carefully.
+
+The following outlines the additional conventions that are used
+in gnome-shell (and mutter).
+
+[handbook]: https://handbook.gnome.org/development/commit-messages.html
+
+## Example
+
+```
+status/volume: Automatically mute in vacuum
+
+In space, no one can hear you scream. There is no point
+in emitting sound that cannot be perceived, so automatically
+mute all output streams.
+
+Closes: https://gitlab.gnome.org/GNOME/gnome-shell/-/issues/1234
+```
+
+## Description
+
+Try to always prefix commit subjects with a relevant topic, such
+as `overview:` or `st/actor:`. Less specific changes can use more
+general topics such as `st` or `js`.
+
+As a general rule, it is always better to write too much in the
+commit message body than too little.
+
+## References
+
+References should always be expressed as full URL instead of the
+`#1234` shorthand, so they still work outside the GitLab UI.
+
+To close an issue automatically, we prefer the `Closes:` keyword
+over the alternatives (see next section).
+
+If a merge requests consists of multiple commits and none of them
+fixes the issue completely, use the plain issue URL without prefix
+as reference, and use the automatic issue closing syntax in the
+description of the merge request.
+
+Do not add any `Part-of:` line, as that will be handled automatically
+when merging.
+
+## The Fixes tag
+
+If a commit fixes a regression caused by a particular commit, it
+can be marked with the `Fixes:` tag. To produce such a tag, use
+
+```
+git show -s --pretty='format:Fixes: %h ("%s")' <COMMIT>
+```
+
+or create an alias
+
+```
+git config --global alias.fixes "show -s --pretty='format:Fixes: %h (\"%s\")'"
+```
+
+and then use
+
+```
+git fixes <COMMIT>
+```